﻿/* 
 * Copyright (C) 2014 Mehdi El Gueddari
 * http://mehdi.me
 *
 * This software may be modified and distributed under the terms
 * of the MIT license.  See the LICENSE file for details.
 */

using System;
using System.Data;

namespace EntityFramework.DbContextScope.Interfaces
{
    /// <summary>
    /// Convenience methods to create a new ambient DbContextScope. This is the preferred method
    /// to create a DbContextScope.
    /// </summary>
    public interface IDbContextScopeFactory
    {
        /// <summary>
        /// Creates a new DbContextScope.
        /// 
        /// By default, the new scope will join the existing ambient scope. This
        /// is what you want in most cases. This ensures that the same DbContext instances
        /// are used by all services methods called within the scope of a business transaction.
        /// 
        /// Set 'joiningOption' to 'ForceCreateNew' if you want to ignore the ambient scope
        /// and force the creation of new DbContext instances within that scope. Using 'ForceCreateNew'
        /// is an advanced feature that should be used with great care and only if you fully understand the
        /// implications of doing this.
        /// 
        ///创建新的DbContextScope。
        ///
        ///默认情况下，新作用域将加入现有环境作用域。这个
        ///在大多数情况下都是你想要的。这确保了相同的DbContext实例
        ///由业务事务范围内调用的所有服务方法使用。
        ///
        ///如果要忽略环境作用域，请将“joiningOption”设置为“ForceCreateNew”
        ///并强制在该范围内创建新的DbContext实例。使用“ForceCreateNew”
        ///是一项高级功能，只有在您完全理解
        ///这样做的意义。
        ///</summary>
        IDbContextScope Create(DbContextScopeOption joiningOption = DbContextScopeOption.JoinExisting);

        /// <summary>
        /// Creates a new DbContextScope for read-only queries.
        /// 
        /// By default, the new scope will join the existing ambient scope. This
        /// is what you want in most cases. This ensures that the same DbContext instances
        /// are used by all services methods called within the scope of a business transaction.
        /// 
        /// Set 'joiningOption' to 'ForceCreateNew' if you want to ignore the ambient scope
        /// and force the creation of new DbContext instances within that scope. Using 'ForceCreateNew'
        /// is an advanced feature that should be used with great care and only if you fully understand the
        /// implications of doing this.
        /// 
        ///为只读查询创建新的DbContextScope。
        ///
        ///默认情况下，新作用域将加入现有环境作用域。这个
        ///在大多数情况下都是你想要的。这确保了相同的DbContext实例
        ///由业务事务范围内调用的所有服务方法使用。
        ///
        ///如果要忽略环境作用域，请将“joiningOption”设置为“ForceCreateNew”
        ///并强制在该范围内创建新的DbContext实例。使用“ForceCreateNew”
        ///是一项高级功能，只有在您完全理解
        ///这样做的意义。
        /// </summary>
        IDbContextReadOnlyScope CreateReadOnly(DbContextScopeOption joiningOption = DbContextScopeOption.JoinExisting);

        /// <summary>
        /// Forces the creation of a new ambient DbContextScope (i.e. does not
        /// join the ambient scope if there is one) and wraps all DbContext instances
        /// created within that scope in an explicit database transaction with 
        /// the provided isolation level. 
        /// 
        /// WARNING: the database transaction will remain open for the whole 
        /// duration of the scope! So keep the scope as short-lived as possible.
        /// Don't make any remote API calls or perform any long running computation 
        /// within that scope.
        /// 
        /// This is an advanced feature that you should use very carefully
        /// and only if you fully understand the implications of doing this.
        /// 
        ///强制创建新的环境DbContextScope（即
        ///如果存在环境作用域，则加入该作用域）并包装所有DbContext实例
        ///在该作用域内的显式数据库事务中创建
        ///提供的隔离级别。
        ///
        ///警告：整个数据库事务将保持打开状态
        ///范围持续时间！因此，要尽可能地缩短范围。
        ///不要进行任何远程API调用或执行任何长时间运行的计算
        ///在这个范围内。
        ///
        ///这是一个高级功能，您应该非常小心地使用它

        ///只有当你完全理解这样做的含义。
        /// </summary>
        IDbContextScope CreateWithTransaction(IsolationLevel isolationLevel);

        /// <summary>
        /// Forces the creation of a new ambient read-only DbContextScope (i.e. does not
        /// join the ambient scope if there is one) and wraps all DbContext instances
        /// created within that scope in an explicit database transaction with 
        /// the provided isolation level. 
        /// 
        /// WARNING: the database transaction will remain open for the whole 
        /// duration of the scope! So keep the scope as short-lived as possible.
        /// Don't make any remote API calls or perform any long running computation 
        /// within that scope.
        /// 
        /// This is an advanced feature that you should use very carefully
        /// and only if you fully understand the implications of doing this.
        /// 
        ///强制创建新的环境只读DbContextScope（即
        ///如果存在环境作用域，则加入该作用域）并包装所有DbContext实例
        ///在该作用域内的显式数据库事务中创建
        ///提供的隔离级别。
        ///
        ///警告：整个数据库事务将保持打开状态
        ///范围持续时间！因此，要尽可能地缩短范围。
        ///不要进行任何远程API调用或执行任何长时间运行的计算
        ///在这个范围内。
        ///
        ///这是一个高级功能，您应该非常小心地使用它
        ///只有当你完全理解这样做的含义。
        /// </summary>
        IDbContextReadOnlyScope CreateReadOnlyWithTransaction(IsolationLevel isolationLevel);

        /// <summary>
        /// Temporarily suppresses the ambient DbContextScope. 
        /// 
        /// Always use this if you need to  kick off parallel tasks within a DbContextScope. 
        /// This will prevent the parallel tasks from using the current ambient scope. If you
        /// were to kick off parallel tasks within a DbContextScope without suppressing the ambient
        /// context first, all the parallel tasks would end up using the same ambient DbContextScope, which 
        /// would result in multiple threads accesssing the same DbContext instances at the same 
        /// time.
        /// 
        ///暂时禁止环境DbContextScope。
        ///
        ///如果需要启动DbContextScope中的并行任务，请始终使用此选项。
        ///这将阻止并行任务使用当前环境作用域。如果你
        ///在DbContextScope中启动并行任务而不抑制环境
        ///首先，所有并行任务都将使用相同的环境DbContextScope，它
        ///会导致多个线程同时访问同一个DbContext实例
        ///时间。
        /// </summary>
        IDisposable SuppressAmbientContext();
    }
}
